home *** CD-ROM | disk | FTP | other *** search
/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / utility / 252 / gemsrc / file.def < prev    next >
Text File  |  1988-02-13  |  11KB  |  248 lines
  1. DEFINITION MODULE File;
  2.  
  3.    (* This module defines data types and procedures for performing *)
  4.    (* DIRECT ACCESS file I/O with a user defined logical record.   *)
  5.  
  6.  
  7.    FROM SYSTEM IMPORT ADDRESS;
  8.    IMPORT GEMDOS;
  9.  
  10.  
  11.    CONST
  12.       EOK           = GEMDOS.EOK;
  13.       UnknownError  = GEMDOS.Error;
  14.       InvalidHandle = GEMDOS.EIHndl;
  15.       BadRequest    = GEMDOS.EBadRq;
  16.       SeekError     = GEMDOS.ESeek;
  17.       ReadFailure   = GEMDOS.EReadF;
  18.       WriteFailure  = GEMDOS.EWritF;
  19.       EndOfFile     = -1000;
  20.  
  21.  
  22.    TYPE RecordIdType = LONGCARD;
  23.  
  24.       (* Defines a type for uniquely identifying a single record. *)
  25.  
  26.    TYPE PossibleFields = (NextKey, PrevKey, NextRecord, PrevRecord);
  27.  
  28.    TYPE RecordHeaderType = RECORD
  29.       NextKeyId    : RecordIdType; (* Id of previous record with different primary key *)
  30.       PrevKeyId    : RecordIdType; (* Id of next record with different primary key *)
  31.       NextRecordId : RecordIdType; (* Id of next logical record *)
  32.       PrevRecordId : RecordIdType; (* Id of previous logical record *)
  33.    END;
  34.  
  35.       (* This declaration, defining information required by the File   *)
  36.       (* module, is provided for inclusion in the user defined record  *)
  37.       (* as the first component.  Immediately following this type, the *)
  38.       (* user must declare two additional fields - a key and a subkey. *)
  39.       (* Each field should be declared as ARRAY [0..n] OF CHAR, where  *)
  40.       (* n is the length of the key (or subkey).  An example of a      *)
  41.       (* complete user defined record is :                             *)
  42.       (*                                                               *)
  43.       (*    TYPE UserDefinedRecord = RECORD                            *)
  44.       (*       RecordHeader : File.RecordHeaderType;                   *)
  45.       (*       Key          : ARRAY [0..3] OF CHAR;                    *)
  46.       (*       SubKey       : ARRAY [0..5] OF CHAR;                    *)
  47.       (*       UserData     : SomeUserDefinedType;                     *)
  48.       (*    END;                                                       *)
  49.  
  50.    TYPE GetKeyProc = PROCEDURE ( ADDRESS, VAR ARRAY OF CHAR );
  51.  
  52.       (* Defines a type for retrieving the key from the user record. *)
  53.  
  54.    TYPE GetSubKeyProc = PROCEDURE ( ADDRESS, VAR ARRAY OF CHAR );
  55.  
  56.       (* Defines a type for retrieving the subkey from the user record. *)
  57.  
  58.    TYPE FileIdType = RECORD
  59.       Valid         : BOOLEAN;       (* True if valid file handle *)
  60.       FileHandle    : INTEGER;       (* GEMDOS file handle *)
  61.       FileSize      : LONGCARD;      (* "High Water" mark of file size *)
  62.       FilePosition  : RecordIdType;  (* Id of current record *)
  63.       RecordSize    : CARDINAL;      (* Size of user defined logical record *)
  64.       NumberRecords : LONGCARD;      (* Number of logical records in file *)
  65.       GetKey        : GetKeyProc;
  66.       GetSubKey     : GetSubKeyProc;
  67.       FreeListId    : RecordIdType;  (* First free record id *)
  68.       FirstRecordId : RecordIdType;  (* First data record id *)
  69.       NextRecordId  : RecordIdType;  (* Id of next record relative to current *)
  70.       PrevRecordId  : RecordIdType;  (* Id of previous record relative to current *)
  71.    END;
  72.  
  73.       (* Defines a type for uniquely identifying a single file.  Note *)
  74.       (* that this type is private to the File module, and as such    *)
  75.       (* must not be modified by other modules.  However, information *)
  76.       (* may be read from the record without adverse side effects.    *)
  77.  
  78.  
  79.    VAR Status : INTEGER;
  80.  
  81.       (* Contains the status of the last File operation. The possible *)
  82.       (* values are documented in module GEMDOS.                      *)
  83.  
  84.  
  85.    PROCEDURE DosError ( ErrorCode : INTEGER );
  86.  
  87.       (* Display the Dos Error in an alert box. *)
  88.  
  89.  
  90.    PROCEDURE GetField (
  91.       Field      : (* IN *) PossibleFields;
  92.       UserRecord : (* IN *) ADDRESS ) : RecordIdType;
  93.  
  94.       (* Retrieves the information from the record header *)
  95.       (* field specified by Field.                        *)
  96.  
  97.  
  98.    PROCEDURE Create (
  99.       VAR FileName   : (* IN *)  ARRAY OF CHAR;
  100.       RecordSize     : (* IN *)  CARDINAL;
  101.       GetKey         : (* IN *)  GetKeyProc;
  102.       GetSubKey      : (* IN *)  GetSubKeyProc;
  103.       VAR FileId     : (* OUT *) FileIdType );
  104.  
  105.       (* Creates a zero length disk file with name FileName.      *)
  106.       (* RecordSize contains the total size of the user defined   *)
  107.       (* record in bytes, and must be larger than the sum of the  *)
  108.       (* sizes of the record header, key, and subkey.  If the     *)
  109.       (* routine was successful, FileId contains a value uniquely *)
  110.       (* identifying the file for further access.                 *)
  111.  
  112.  
  113.    PROCEDURE Open (
  114.       VAR FileName   : (* IN *)  ARRAY OF CHAR;
  115.       GetKey         : (* IN *)  GetKeyProc;
  116.       GetSubKey      : (* IN *)  GetSubKeyProc;
  117.       VAR FileId     : (* OUT *) FileIdType );
  118.  
  119.       (* Opens the existing file named FileName.  Note that since  *)
  120.       (* the file attributes are stored in the file (record size,  *)
  121.       (* key size, subkey size, etc), this information does not    *)
  122.       (* need to be specified by the user when invoking this       *)
  123.       (* routine.  If the routine was successful, FileId contains  *)
  124.       (* a value uniquely identifying the file for further access. *)
  125.  
  126.  
  127.    PROCEDURE Read (   
  128.       VAR FileId   : (* IN *)  FileIdType;  
  129.       Data         : (* OUT *) ADDRESS;
  130.       VAR RecordId : (* OUT *) RecordIdType );
  131.  
  132.       (* Reads the record located at the current file position     *)
  133.       (* into Data.  If the routine is successful, the record id   *)
  134.       (* is placed in RecordId.  Otherwise, the contents of        *)
  135.       (* RecordId is undefined.  Upon completion of this routine,  *)
  136.       (* the current file position is advanced to the next logical *)
  137.       (* record.                                                   *)
  138.  
  139.  
  140.    PROCEDURE Write (
  141.       VAR FileId   : (* IN *)  FileIdType;  
  142.       Data         : (* IN *)  ADDRESS;
  143.       VAR RecordId : (* OUT *) RecordIdType );
  144.  
  145.       (* Writes the contents of Data into the record located at the    *)
  146.       (* current file position.  If the routine is successful, the     *)
  147.       (* record id is placed in RecordId.  Otherwise, the contents of  *)
  148.       (* RecordId is undefined.  Upon completions of this routine, the *)
  149.       (* current file position is advanced to the next logical record. *)
  150.       (* Note that the contents of the key and subkey fields must not  *)
  151.       (* be changed since the record was last read.  In order to       *)
  152.       (* modify the contents of the key or subkey, delete the record   *)
  153.       (* and then reinsert it.  This will reinsert the record in the   *)
  154.       (* proper place in the file.                                     *)
  155.         
  156.  
  157.    PROCEDURE InsertRecord (
  158.       VAR FileId   : (* IN *)  FileIdType;  
  159.       VAR Key      : (* IN *)  ARRAY OF CHAR;
  160.       VAR SubKey   : (* IN *)  ARRAY OF CHAR;
  161.       Data         : (* IN *)  ADDRESS;
  162.       WorkBuffer   : (* IN *)  ADDRESS;
  163.       VAR RecordId : (* OUT *) RecordIdType );
  164.  
  165.       (* Inserts the contents of Data into the file associated with    *)
  166.       (* FileId.  The record is inserted into the file in ascending    *)
  167.       (* ASCII order (based on the contents of the key and subkey).    *)
  168.       (* If the routine is successful, RecordId contains a value       *)
  169.       (* uniquely identifying the record.  Otherwise, the contents     *)
  170.       (* of RecordId is undefined.  Note that the parameter            *)
  171.       (* WorkBuffer, used internally by the routine for temporary      *)
  172.       (* storage, must be of the same type as the user defined record. *)
  173.  
  174.  
  175.    PROCEDURE DeleteRecord (   
  176.       VAR FileId : (* IN *) FileIdType;  
  177.       RecordId   : (* IN *) RecordIdType;
  178.       WorkBuffer : (* IN *) ADDRESS );
  179.  
  180.       (* Deletes the record identified by RecordId from the file      *)
  181.       (* associated with FileId.  Note that the parameter WorkBuffer, *)
  182.       (* used internally by the routine for temporary storage, must   *)
  183.       (* be of the same type as the user defined record.              *)
  184.  
  185.  
  186.    PROCEDURE Retreat (
  187.       VAR FileId   : (* IN *)  FileIdType;  
  188.       Data         : (* OUT *) ADDRESS;
  189.       VAR RecordId : (* OUT *) RecordIdType );
  190.  
  191.       (* Moves the current file position to the previous logical    *)
  192.       (* record and then places the contents of the record in Data. *)
  193.       (* If the routine is successful, the id of the record is      *)
  194.       (* placed in RecordId.  Otherwise, the contents of RecordId   *)
  195.       (* is undefined.  Note that the parameter WorkBuffer, used    *)
  196.       (* internally by the routine for temporary storage, must be   *)
  197.       (* of the same type as the user defined record.               *)
  198.  
  199.  
  200.    PROCEDURE Seek (
  201.       VAR FileId : (* IN *)  FileIdType;
  202.       RecordId   : (* IN *)  RecordIdType;
  203.       Data       : (* OUT *) ADDRESS );
  204.  
  205.       (* Moves the current file position to the record identified by   *)
  206.       (* RecordId, and then places the contents of the record in Data. *)
  207.  
  208.  
  209.    PROCEDURE Find (
  210.       VAR FileId      : (* IN *)  FileIdType;
  211.       VAR Key         : (* IN *)  ARRAY OF CHAR;
  212.       VAR SubKey      : (* IN *)  ARRAY OF CHAR;  
  213.       Data            : (* OUT *) ADDRESS;
  214.       VAR FoundKey    : (* OUT *) BOOLEAN;
  215.       VAR KeyId       : (* OUT *) RecordIdType;
  216.       VAR FoundRecord : (* OUT *) BOOLEAN;
  217.       VAR RecordId    : (* OUT *) RecordIdType );
  218.  
  219.       (* Searches the file associated with FileId for a record      *)
  220.       (* containing the contents of Key and Subkey.  Note that      *)
  221.       (* either of the keys may be a null string - matching any     *)
  222.       (* record.  If a record was found, the contents of the record *)
  223.       (* is placed in Data, and RecordId is set to a value uniquely *)
  224.       (* identifying the record.  The current file position is then *)
  225.       (* set to the start of the next record.  Otherwise, if the    *)
  226.       (* keys could not be found, the contents of RecordId are      *)
  227.       (* undefined, with KeyId and RecordId pointing to the last    *)
  228.       (* key and record read during the search, respectively.       *)
  229.  
  230.  
  231.    PROCEDURE Close ( VAR FileId : (* IN *) FileIdType );
  232.  
  233.       (* Closes the file associated with FileId. *)
  234.  
  235.  
  236.    PROCEDURE Copy;
  237.  
  238.       (* Copy one file to another. *)
  239.  
  240.  
  241.    PROCEDURE Delete;
  242.  
  243.       (* Delete a file. *)
  244.  
  245.  
  246. END File.
  247.  
  248.